home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_asm / nnansi3 / nnansi.doc < prev    next >
Text File  |  1990-03-07  |  14KB  |  280 lines
  1. nnansi   - enhanced MS-DOS ansi console driver for EGA/VGA displays
  2.  
  3. SYNOPSIS
  4.         Include in \config.sys the line
  5.                 device=nnansi.sys
  6.  
  7. DESCRIPTION
  8.     nnansi.sys is a NEW version of nansi.sys for the EGA/VGA display.
  9.     Its advantages over nansi.sys are:
  10.     1. It supports erase to start/end of screen control sequences.
  11.     2. It (optionally) scrolls by reprogramming the display controller
  12.        for 10-20x speed improvement dumping files to the display.
  13.     3. It understands display heights other than 25 and 43, thus is
  14.        useful in all extended EGA and VGA modes.
  15.     4. INT29 operation is typically 15% faster
  16.     5. Set Graphic Rendition reverse video now actually exchanges
  17.        foreground and background.  In reverse video mode, changing the
  18.        background color alters the displayed foreground and visa-versa.
  19.        New code added to turn off bold and blink (and sorta turn off
  20.        "underline").
  21.     6. Some code cleanup has been performed (but not much)
  22.     7. There are more assembly options -- BE SURE TO LOOK AT NNANSI_D.ASM.
  23.     8. Graphic cursor can be disabled.  Graphic cursor logic completely
  24.        changed -- BIOS set cursor position call will no longer leave 
  25.        cursor ghosts.  (Note that for some programs it will be necessary
  26.        to disable the graphics cursor; No cursor is the "standard", but
  27.        having the cursor is so much nicer that it is the default).
  28. Compared to 1/8/89 version of NNANSI.SYS:
  29.     1. NNANSI is capable of writing characters directly to the screen
  30.        (without using the BIOS) in the 640x350 and 640x480 16 color modes,
  31.        and other 16 color modes with slight modification. This speeds up
  32.        character writing to 56% of NANSI's times.
  33.     2. Keyboard redefinition can be disabled.
  34.     3. Handling of the graphic cursor is somewhat better than before.
  35.     4. There are configuration options for several popular display cards
  36.        which allows improved performance in extended graphic or alpha
  37.            modes. 
  38.  
  39.  
  40. ********BE SURE TO READ SECTION "BUGS" BELOW BEFORE USING!!!!
  41.  
  42.     [What follows is a modified copy of the original nansi.sys
  43.      documentation]
  44.  
  45.         nnansi.sys is a console driver which understands ANSI control
  46.         sequences. It has several advantages over ANSI.SYS (the driver
  47.         supplied with DOS):
  48.         1. It supports new escape sequences (see below).
  49.         2. It provides MUCH faster output under certain conditions.
  50.         3. It supports the 43-line mode of the EGA/VGA, and all EGA/VGA
  51.        extended modes (mode must be changed with other program).  There
  52.        is now no need to use the vendor supplied nansi.sys drivers that
  53.        come with various display cards.
  54.         4. The darned bell is now 1/4 second instead of 1/2 second long.
  55.  
  56.         What a console driver does:
  57.         When you, for example, type
  58.                 C:> type foo.txt
  59.         COMMAND.COM opens the file foo.txt, reads it, and writes it to
  60.         the console driver, which puts it up on the screen.
  61.  
  62.         Both ansi.sys and nnansi.sys use IBM Video BIOS to control the screen.
  63.         However, nnansi.sys bypasses BIOS if the screen is in a text mode or
  64.     16 color EGA/VGA graphic modes; 
  65.     this allows much faster operation under certain conditions.  Also
  66.     nnansi.sys scrolls by reprogramming the display start address rather
  67.     than moving all of the characters.
  68.  
  69.         While putting text up on the screen, (nn)ansi.sys keeps a lookout for
  70.         the escape character (chr(27), known as ESC); this character signals
  71.         the start of a terminal control sequence.
  72.         Terminal control sequences follow the format
  73.                 ESC [ param; param; ...; param cmd
  74.         where
  75.                 ESC     is the escape character chr$(27).
  76.                 [       is the left bracket character.
  77.                 param   is an ASCII decimal number, or a string in quotes.
  78.                 cmd     is a case-specific letter identifying the command.
  79.         Usually, zero, one, or two parameters are given.  If parameters
  80.         are omitted, they usually default to 1; however, some commands
  81.         (KKR and DKOCT) treat the no-parameter case specially.
  82.         Spaces are not allowed between parameters.
  83.  
  84.         For example, both ESC[1;1H and ESC[H send the cursor to the home
  85.         position (1,1), which is the upper left.
  86.  
  87.         Either single or double quotes may be used to quote a string.
  88.         Each character inside a quoted string is equivalent to one numeric
  89.         parameter.  Quoted strings are normally used only for the Keyboard
  90.         Key Reassignment command.
  91.  
  92. Control Sequences
  93.         The following table lists the sequences understood by nnansi.sys.
  94.         Differences between nnansi.sys and the standard ansi.sys are marked
  95.         with a vertical bar (|).
  96.  
  97. Cursor Positioning
  98. Short   Long name               Format          Notes
  99. CUP     cursor position         ESC[y;xH        Sets cursor position.
  100. HVP     cursor position         ESC[y;xf        Same as CUP; not recommended.
  101. CUU     cursor up               ESC[nA          n = # of lines to move
  102. CUD     cursor down             ESC[nB
  103. CUF     cursor forward          ESC[nC          n = # of columns to move
  104. CUB     cursor backward         ESC[nD
  105. DSR     Device Status, Report!  ESC[6n          Find out cursor position.
  106. CPR     Cursor Position report  ESC[y;xR        Response to DSR, as if typed.
  107. SCP     Save Cursor Position    ESC[s           Not nestable.
  108. RCP     Restore Cursor Position ESC[u
  109.  
  110. Editing
  111. ED  |   Erase in Display        ESC[0J or ESC[J Clear to end of screen
  112.     |                ESC[1J    Clear to start of screen
  113.                 ESC[2J  Clears screen.
  114. EL      Erase in Line           ESC[K   Clears to end of line.
  115. IL  |   Insert Lines            ESC[nL  Inserts n blank lines at cursor line.
  116. DL  |   Delete Lines            ESC[nM  Deletes n lines including cursor line.
  117. ICH |   Insert Characters       ESC[n@  Inserts n blank chars at cursor.
  118. DCH |   Delete Characters       ESC[nP  Deletes n chars including cursor char.
  119.  
  120.  
  121. Mode-Setting
  122. SGR     Set Graphics Rendition  ESC[n;n;...nm   See character attribute table.
  123. SM      Set Mode                ESC[=nh         See screen mode table.
  124. RM      Reset Mode              ESC[=nl         See screen mode table.
  125. IBMKKR  Keyboard Key Reass.     ESC["string"p
  126.         The first char of the string gives the key to redefine; the rest
  127.         of the string is the key's new value.
  128.         To specify unprintable chars, give the ASCII value of the char
  129.         outside of quotes, as a normal parameter.
  130.         IBM function keys are two byte strings; see the IBM Basic manual.
  131.         For instance, ESC[0;";dir a:";13;p redefines function key 1 to
  132.         have the value "dir a:" followed by the ENTER key.
  133.       | If no parameters given, all keys are reset to their default values.
  134.  
  135. DKOCT | Output char translate   ESC[n;ny
  136.       | When first char is encountered in output request, it is replaced with
  137.       | the second char.  This might be useful for previewing text before
  138.       | sending it to a printer with a funny print wheel.
  139.       | If no parameters are given, all chars are reset to normal.
  140.  
  141.  
  142. Character Attributes
  143.         The Set Graphics Rendition command is used to select foreground
  144.         and background colors or attributes.
  145.         When you use multiple parameters, they are executed in sequence, and
  146.         the effects are cumulative.
  147.            Attrib code          Value
  148.                 0               All attributes off (normal white on black)
  149.                 1               Bold
  150. |        2        Dim (not Bold)
  151.                 4               Underline (blue foreground)
  152.                 5               Blink
  153.                 7               Reverse Video
  154.                 8               Invisible (but why?)
  155. |        22        Cancel Bold
  156. |        24        Cancel Underline (white foreground)
  157. |        25        Cancel Blink
  158. |        27        Normal, un-reversed video
  159.                 30-37           foregnd blk/red/grn/yel/blu/magenta/cyan/white
  160.                 40-47           background
  161.  
  162. Screen Modes
  163.         The IBM BIOS supports several video modes; the codes given in the
  164.         BIOS documentation are used as parameters to the Set Mode command.
  165.       | (In bitmap modes, the cursor is simulated with a small blob (^V).)
  166.             Mode Code           Value
  167.                 0               text 40x25 Black & White
  168.                 1               text 40x25 Color
  169.                 2               text 80x25 Black & White
  170.                 3               text 80x25 Color
  171.                 4               bitmap 320x200 4 bits/pixel
  172.                 5               bitmap 320x200 1 bit/pixel
  173.                 6               bitmap 640x200 1 bit/pixel
  174.                 7               (cursor wrap kludge)
  175.                 13              bitmap 320x200 4 bits/pixel
  176.                 14              bitmap 640x200 4 bits/pixel
  177.                 16              bitmap 640x350 4 bits/pixel
  178. |        17 (VGA)    bitmap 640x480 1 bit/pixel
  179. |        18 (VGA)    bitmap 640x480 4 bits/pixel
  180. |        19 (VGA)        bitmap 300x200 8 bits/pixel
  181. |        99        (graphics cursor kludge)
  182.         Mode 7 is an unfortunate kludge; Setting mode 7 tells the cursor
  183.         to wrap around to the next line when it passes the end of a line;
  184.         Resetting mode 7 tells the cursor to not wrap, but rather stay put.
  185. |    Mode 99 enables the graphics mode cursor.
  186.       | NNANSI.SYS supports all EGA/VGA modes
  187.       | The EGA also lets you use a shorter character cell in text modes
  188.       | in order to squeeze 43 lines of text out of the 25-line text modes.
  189.       | To enter 43 line mode, set the desired 25-line text mode (0 to 3),
  190.       | then Set Mode 43.  For instance: ESC[=3h ESC[=43h.
  191.       | To exit 43 line mode, set the desired 25-line text mode again.
  192.  
  193.  
  194.       | The driver supports all extended modes available with most EGA/VGA
  195.       | boards, such as 132 column modes and 60 line modes.  These modes
  196.       | currently must be set by a vendor supplied program.  (Why couldn't
  197.       | there be a standard for these??)
  198.  
  199.  
  200. Faster Output
  201.       | Any program that sets the console to RAW mode, and buffers its
  202.       | output properly, can achieve extremely high screen update speeds in
  203.       | return for giving up the special functions of the keys ^C, ^S, and ^P.
  204.       | See IOCTL in the MS-DOS 3.x Technical Reference for more info.
  205.         Also, a small improvement in speed may be noticed with some
  206.         programs that use the DOS console in normal mode, as this driver
  207.         efficiently implements the (standard but undocumented) INT 29h
  208.         most-favored-device putchar used by DOS.
  209.  
  210. EXAMPLES
  211.         See the file setraw.doc for Macro Assembler, Lattice C,
  212.         and Microsoft C routines for entering and leaving raw mode.
  213.  
  214. BUGS
  215.         Insert and delete character do not work in graphics modes.
  216.  
  217.     Tabs are expanded in RAW mode.  This could also be viewed as a
  218.     feature, so I (Tom Almy) did not correct the problem.
  219.  
  220.         Does not support some useful ANSI functions.
  221.  
  222.     The Graphics Cursor may be incompatible with some graphics programs.
  223.     The cure is to turn the graphics cursor off.
  224.  
  225.     The "fast" option in nnansi_d.asm (which is the default) scrolls the
  226.     display by reprogramming the display controller rather than moving
  227.     the contents of the display memory.  While this is considerably 
  228.     faster, most programs that access the display directly assume that
  229.     the display memory starts at B800:0 rather than using the starting
  230.     address stored at 40:4E.  NNANSI resets the display starting address
  231.     to B800:0 whenever the BIOS is used to clear the display or return
  232.     the display mode.  This seems to handle most programs, but 
  233.     unfortunately there are some "dirty" programs out there that access
  234.     the display directly and never issue a BIOS call!  These programs
  235.     can still usually be run by executing the DOS command CLS first.
  236.     Otherwise you will have to reassemble the driver with "fast EQU 0"
  237.     and take a major performance penalty.  Known culprits include
  238.     PC-WRITE (except when used in 43 line mode), VP-PLANNER and PCTOOLS.
  239.  
  240.     Some display cards set memory location 40:49H to other than 3 when in
  241.     a high resolution alpha mode. Unfortunately NNANSI considers these
  242.     modes to be graphic, and does not work properly. There exists a
  243.         compilation option for Paradise cards, which display this problem.
  244.     If your card displays this problem, but is not listed in the
  245.     nnansi_d.asm file, please send me a note.
  246.  
  247.  
  248. VERSION
  249.     This is NNANSI.SYS version 11/89, by Tom Almy (toma@tekgvs.labs.tek.com).
  250.     It is a modification of:
  251.  
  252.     NNANSI.SYS version 1/8/89, by Tom Almy
  253.  
  254.         NANSI.SYS, version, 2.2, created February 1986.  Problems should
  255.         be reported to Daniel Kegel, 1-60 CIT, Pasadena, CA 91126
  256.         (or, after June 1986, 2648 169th Ave SE, Bellevue, Wa. 98008).
  257.         Your suggestions for improvement would be most welcome.
  258.  
  259. NOTE
  260.         This program may be distributed for educational and personal use
  261.         only.  Commercial use is verboten; get in touch with the author.
  262.     (Tom Almy places no restrictions on his modifications)
  263.  
  264. FILES
  265.     nnansi.sys    - Driver, with compilation options set as shown
  266.             - in the source file nnansi_d.asm
  267.             *** YOU WILL PROBABLY WANT TO RECOMPILE WITH 
  268.                 YOUR CHOICES ***
  269.         nnansi.doc      - this file
  270.         makefile    - shows how to assemble & link
  271.         nnansi_d.asm    - definitions **** READ THIS ****
  272.         nnansi.asm      - device driver guts
  273.         nnansi_p.asm    - ANSI parameter grabber
  274.         nnansi_f.asm    - ANSI function handlers
  275.         nnansi_i.asm    - device driver init routine
  276.  
  277.  
  278. You can assemble with Microsoft MASM or Borland TASM. The makefile is for
  279. NDMAKE and TASM.
  280.